@tensorix/metahub 0.1.10 → 0.2.0

package/README.md

@@ -57,7 +57,7 @@ Output adapts to the audience: a terminal (human) gets tables / Markdown, a pipe
 import { openMetahub, createDatabase, createRecord, search } from "@tensorix/metahub";
 ```
 
-Platforms: `darwin-arm64` / `darwin-x64` / `linux-x64` / `linux-arm64` / `windows-x64`. Library API: see [CONTRIBUTING.md](./CONTRIBUTING.md).
+Platforms: `darwin-arm64` / `darwin-x64` / `linux-x64` / `linux-arm64` / `windows-x64` / `windows-arm64`. Library API: see [CONTRIBUTING.md](./CONTRIBUTING.md).
 
 ## Sync across machines
 
@@ -77,11 +77,19 @@ Pair two devices once and they sync both ways on a timer — no need to run `mh
 
 `mh --server` serves a browser **WebUI** at `/` (browse and inline-edit tables, block-level WYSIWYG document editing, full-text search, manage agent sites). The same server also exposes:
 
-- `/api/*` — REST endpoints over your tables and documents.
+- `/api/*` — REST endpoints over your tables and documents (read **and** write; hosted site pages call them same-origin).
 - `/docs` — auto-generated OpenAPI documentation.
-- `/sites/<name>/` — `mh site publish` hosts the HTML/CSS/JS an agent generates; pages call `/api/*` same-origin to read your data (a local mini-Supabase).
+- `/sites/<name>/` — `mh site publish` hosts the HTML/CSS/JS an agent generates; pages call `/api/*` same-origin, or import the optional typed client at `/metahub-sdk.js` (a local mini-Supabase). Note the trust model: hosted pages are same-origin, so any published site effectively holds full hub access — publish only sites you or your agent authored.
 
-Requests are guarded by a single token (persisted in `~/.metahub`). The server binds `127.0.0.1` by default; only `--host 0.0.0.0` exposes it, and credentials travel as plaintext Bearer — put it behind a trusted network or TLS. Details in the [system-design docs](./docs/system-design/).
+Requests are guarded by a single token (persisted in `~/.metahub`). The server binds `127.0.0.1` by default; only `--host 0.0.0.0` exposes it, and credentials travel as plaintext Bearer — put it behind a trusted network or TLS (a reverse proxy like Caddy / Tailscale Serve, or `--tls-cert`/`--tls-key` to terminate TLS directly). Details in the [system-design docs](./docs/system-design/).
+
+## Offline (PWA): the browser as a sync node
+
+The WebUI is an installable PWA. Open **Settings → 离线副本** and this browser pairs with the server (an individually revocable credential), hydrates a **full local replica** (SQLite-in-OPFS running the same core), and from then on reads/writes go local with background `/sync` — on a weak network or fully offline you can still view **and edit everything**, including documents, tables, and hosted sites you never opened; changes merge block-level when connectivity returns. Notes:
+
+- Needs HTTPS (service workers require a secure context) and a browser with OPFS (Safari 17+, Chrome, Firefox); unsupported browsers transparently stay plain online clients.
+- On iPhone, add the app to the home screen — Safari evicts storage for regular tabs after ~7 days of disuse; home-screen apps are exempt.
+- The first hydration must happen online; afterwards any tab (one leader per browser, others proxy to it) serves the data, and hosted site pages work offline too — reads and writes included.
 
 ## Command reference
 
@@ -100,10 +108,15 @@ Requests are guarded by a single token (persisted in `~/.metahub`). The server b
 | `mh doc read <id>` | Read body + version token (AI reads before editing) |
 | `mh doc edit <id> --old --new` | Anchored find-and-replace (`--replace-all` / `--if-match`) |
 | `mh doc append\|prepend <id> --body` | Append a block at the document head/tail |
+| `mh doc history <id>` / `mh doc revert <id> --to <version>` | List a document's revisions / restore a past version (a new forward revision; `doc get --at <version>` previews; revert resurrects a deleted doc) |
+| `mh record history <id> [--field <name>]` / `mh record revert <id> --to <version>` | Record edit history (per-revision field diffs, or one cell's value trail) / restore past cells (resurrects a deleted record) |
+| `mh prop history <id>` / `mh prop revert <id> --to <version>` | Column definition history / schema rollback: restores the column **and** the cells its type-change/removal cleared, keeping user edits made since |
+| `mh db activity [<id>] [--limit N]` | Table activity feed: every record's revisions merged newest-first, each with old→new cell values and a record-title snapshot (deleted records show their last title) |
 | `mh edit <id>` | Edit a document/record interactively in `$EDITOR` (for humans) |
 | `mh search <query>` | Full-text search (documents + records) |
-| `mh doctor` | Read-only health check: list integrity issues (orphan refs/cells, duplicate paths, doc cycles, name clashes) |
+| `mh doctor` | Read-only health check: list integrity issues (orphan refs/cells, duplicate paths, doc cycles, name clashes) + oplog/disk stats |
 | `mh repair [--dry-run]` | Deterministic, idempotent repair of auto-fixable issues (changes replicate via oplog); `--dry-run` previews (same as doctor) |
+| `mh compact [--keep <days>] [--dry-run]` | Prune oplog history older than the retention window (default 90d) + GC blobs + VACUUM. Local-only; current data untouched, older history collapses to a baseline |
 | `mh site create\|put\|publish\|list\|files\|rm\|delete` | Host static sites (HTML/CSS/JS) an agent generates, served by `--server` at `/sites/<name>/` |
 | `mh token [show\|refresh]` | Show/rotate the persisted server auth token (stored in `~/.metahub`, rotates at 30-day expiry by default) |
 | `mh completion <bash\|zsh\|fish>` | Print a completion script: `eval "$(mh completion zsh)"` |
@@ -112,7 +125,7 @@ Requests are guarded by a single token (persisted in `~/.metahub`). The server b
 | `mh config` | Configure the server and sync devices: no args opens an interactive wizard, `--flag` sets directly (`--host/--port/--sync-interval/--auto-sync`) |
 | `mh config peer code\|add\|list\|sync\|enable\|disable\|rm` | Multi-device pairing and management: generate a one-time code / pair / list / sync now / enable-disable / remove (also revokes the credential issued to the peer) |
 | `mh config grant list\|revoke` | List/revoke inbound sync credentials this machine issued (`revoke --token` accepts an exact value or prefix) |
-| `mh --server [--port] [--host] [--debug] [--token] [--sync-interval] [--no-auto-sync]` | Start the server: `/sync` (master token or pairing credential) + WebUI at `/` + `/api/*` REST + `/docs` (OpenAPI) + static sites `/sites/<name>/` + token exchange `/auth/token` + pairing `/api/pair`; a built-in timer auto-syncs paired peers |
+| `mh --server [--port] [--host] [--debug] [--token] [--sync-interval] [--no-auto-sync] [--tls-cert --tls-key]` | Start the server: `/sync` (master token or pairing credential) + WebUI/PWA at `/` + `/api/*` REST + `/docs` (OpenAPI) + static sites `/sites/<name>/` + token exchange `/auth/token` + pairing `/api/pair`; a built-in timer auto-syncs paired peers; `--tls-*` serves https directly (PEM paths) |
 
 </details>
 

package/README.zh-CN.md

@@ -57,7 +57,7 @@ mh doc append <ref> --body "追加段落"             # 也有 prepend
 import { openMetahub, createDatabase, createRecord, search } from "@tensorix/metahub";
 ```
 
-支持平台：`darwin-arm64` / `darwin-x64` / `linux-x64` / `linux-arm64` / `windows-x64`。库 API 详见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
+支持平台：`darwin-arm64` / `darwin-x64` / `linux-x64` / `linux-arm64` / `windows-x64` / `windows-arm64`。库 API 详见 [CONTRIBUTING.md](./CONTRIBUTING.md)。
 
 ## 多机同步
 
@@ -100,10 +100,15 @@ mh sync http://a-host:7777
 | `mh doc read <id>` | 读正文 + version token（AI 改前先读） |
 | `mh doc edit <id> --old --new` | 锚定查找替换（`--replace-all` / `--if-match`） |
 | `mh doc append\|prepend <id> --body` | 在文档首/尾追加块 |
+| `mh doc history <id>` / `mh doc revert <id> --to <version>` | 列出文档修订历史 / 恢复到某版本（回滚是一次新的正向修订；`doc get --at <version>` 预览；revert 可复活已删文档） |
+| `mh record history <id> [--field <名>]` / `mh record revert <id> --to <version>` | 记录修改历史（逐修订字段 diff，或单字段值变迁）/ 恢复历史值（可复活已删记录） |
+| `mh prop history <id>` / `mh prop revert <id> --to <version>` | 列定义历史 / schema 回滚：同时恢复列定义**和**被改类型/删列清掉的单元格，之后的用户编辑保留 |
+| `mh db activity [<id>] [--limit N]` | 表级活动流：全表记录修订按时间倒序聚合，每条带字段级「旧值 → 新值」与记录标题快照（已删记录显示删除时的标题） |
 | `mh edit <id>` | 在 `$EDITOR` 中交互式编辑文档/记录（给人用） |
 | `mh search <query>` | 全文检索（文档 + 记录） |
-| `mh doctor` | 只读体检：列出逻辑完整性问题（孤儿引用/单元格、重复路径、文档环、重名等） |
+| `mh doctor` | 只读体检：列出逻辑完整性问题（孤儿引用/单元格、重复路径、文档环、重名等）+ oplog/磁盘统计 |
 | `mh repair [--dry-run]` | 确定性、幂等修复可自动修的问题（改动随 oplog 复制）；`--dry-run` 仅预览（等价 doctor） |
+| `mh compact [--keep <天数>] [--dry-run]` | 清理保留窗口（默认 90 天）之外的 oplog 历史 + 回收无引用 blob + VACUUM。纯本地操作；当前数据不变，窗口外历史坍缩为基线（无法再回滚到更早版本） |
 | `mh site create\|put\|publish\|list\|files\|rm\|delete` | 托管 agent 生成的静态站点（HTML/CSS/JS），由 `--server` 在 `/sites/<name>/` serve 出去 |
 | `mh token [show\|refresh]` | 查看 / 轮换持久化的服务器鉴权 token（存于 `~/.metahub`，默认 30 天到期轮换） |
 | `mh completion <bash\|zsh\|fish>` | 打印补全脚本：`eval "$(mh completion zsh)"` |